<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Cluster health API | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="cluster.html" title="Cluster APIs">
<link rel="prev" href="cluster-get-settings.html" title="Cluster get settings API">
<link rel="next" href="cluster-reroute.html" title="Cluster reroute API">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="cluster.html">Cluster APIs</a></span>
»
<span class="breadcrumb-node">Cluster health API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="cluster-get-settings.html">« Cluster get settings API</a>
</span>
<span class="next">
<a href="cluster-reroute.html">Cluster reroute API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="cluster-health"></a>Cluster health API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Returns the health status of a cluster.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">GET _cluster/health/&lt;index&gt;</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The cluster health API returns a simple status on the health of the
cluster. The API can also be executed against one or more indices to get just
the specified indices health.</p>
<p>The cluster health status is: <code class="literal">green</code>, <code class="literal">yellow</code> or <code class="literal">red</code>. On the shard level, a
<code class="literal">red</code> status indicates that the specific shard is not allocated in the cluster,
<code class="literal">yellow</code> means that the primary shard is allocated but replicas are not, and
<code class="literal">green</code> means that all shards are allocated. The index level status is
controlled by the worst shard status. The cluster status is controlled by the
worst index status.</p>
<p>One of the main benefits of the API is the ability to wait until the cluster
reaches a certain high water-mark health level. For example, the following will
wait for 50 seconds for the cluster to reach the <code class="literal">yellow</code> level (if it reaches
the <code class="literal">green</code> or <code class="literal">yellow</code> status before 50 seconds elapse, it will return at that
point):</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/health?wait_for_status=yellow&amp;timeout=50s</pre>
</div>
<div class="console_widget" data-snippet="snippets/1389.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;index&gt;</code>
</span>
</dt>
<dd>
(Optional, string) Comma-separated list or wildcard expression of index names
used to limit the request.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">level</code>
</span>
</dt>
<dd>
(Optional, string) Can be one of <code class="literal">cluster</code>, <code class="literal">indices</code> or <code class="literal">shards</code>. Controls
the details level of the health information returned. Defaults to <code class="literal">cluster</code>.
</dd>
<dt>
<span class="term">
<code class="literal">local</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the request retrieves information from the local
node only. Defaults to <code class="literal">false</code>, which means information is retrieved from
the master node.
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_active_shards</code>
</span>
</dt>
<dd>
(Optional, string) A number controlling to how many active shards to wait
for, <code class="literal">all</code> to wait for all shards in the cluster to be active, or <code class="literal">0</code> to not
wait. Defaults to <code class="literal">0</code>.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_events</code>
</span>
</dt>
<dd>
(Optional, string) Can be one of <code class="literal">immediate</code>, <code class="literal">urgent</code>, <code class="literal">high</code>, <code class="literal">normal</code>,
<code class="literal">low</code>, <code class="literal">languid</code>. Wait until all currently queued events with the given
priority are processed.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_no_initializing_shards</code>
</span>
</dt>
<dd>
(Optional, boolean) A boolean value which controls whether to wait (until
the timeout provided) for the cluster to have no shard initializations.
Defaults to false, which means it will not wait for initializing shards.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_no_relocating_shards</code>
</span>
</dt>
<dd>
(Optional, boolean) A boolean value which controls whether to wait (until
the timeout provided) for the cluster to have no shard relocations. Defaults
to false, which means it will not wait for relocating shards.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_nodes</code>
</span>
</dt>
<dd>
(Optional, string) The request waits until the specified number <code class="literal">N</code> of
nodes is available. It also accepts <code class="literal">&gt;=N</code>, <code class="literal">&lt;=N</code>, <code class="literal">&gt;N</code> and <code class="literal">&lt;N</code>.
Alternatively, it is possible to use <code class="literal">ge(N)</code>, <code class="literal">le(N)</code>, <code class="literal">gt(N)</code> and
<code class="literal">lt(N)</code> notation.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_status</code>
</span>
</dt>
<dd>
(Optional, string) One of <code class="literal">green</code>, <code class="literal">yellow</code> or <code class="literal">red</code>. Will wait (until the
timeout provided) until the status of the cluster changes to the one
provided or better, i.e. <code class="literal">green</code> &gt; <code class="literal">yellow</code> &gt; <code class="literal">red</code>. By default, will not
wait for any status.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-response-body"></a>Response body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">cluster_name</code>
</span>
</dt>
<dd>
(string) The name of the cluster.
</dd>
<dt>
<span class="term">
<code class="literal">status</code>
</span>
</dt>
<dd>
<p>
(string)
Health status of the cluster, based on the state of its primary and replica
shards. Statuses are:
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">green</code>
</span>
</dt>
<dd>
All shards are assigned.
</dd>
<dt>
<span class="term">
<code class="literal">yellow</code>
</span>
</dt>
<dd>
All primary shards are assigned, but one or more replica shards are
unassigned. If a node in the cluster fails, some
data could be unavailable until that node is repaired.
</dd>
<dt>
<span class="term">
<code class="literal">red</code>
</span>
</dt>
<dd>
One or more primary shards are unassigned, so some data is unavailable. This
can occur briefly during cluster startup as primary shards are assigned.
</dd>
</dl>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">timed_out</code>
</span>
</dt>
<dd>
(boolean) If <code class="literal">false</code> the response returned within the period of
time that is specified by the <code class="literal">timeout</code> parameter (<code class="literal">30s</code> by default).
</dd>
<dt>
<span class="term">
<code class="literal">number_of_nodes</code>
</span>
</dt>
<dd>
(integer) The number of nodes within the cluster.
</dd>
<dt>
<span class="term">
<code class="literal">number_of_data_nodes</code>
</span>
</dt>
<dd>
(integer) The number of nodes that are dedicated data nodes.
</dd>
<dt>
<span class="term">
<code class="literal">active_primary_shards</code>
</span>
</dt>
<dd>
(integer) The number of active primary shards.
</dd>
<dt>
<span class="term">
<code class="literal">active_shards</code>
</span>
</dt>
<dd>
(integer) The total number of active primary and replica shards.
</dd>
<dt>
<span class="term">
<code class="literal">relocating_shards</code>
</span>
</dt>
<dd>
(integer) The number of shards that are under relocation.
</dd>
<dt>
<span class="term">
<code class="literal">initializing_shards</code>
</span>
</dt>
<dd>
(integer) The number of shards that are under initialization.
</dd>
<dt>
<span class="term">
<code class="literal">unassigned_shards</code>
</span>
</dt>
<dd>
(integer) The number of shards that are not allocated.
</dd>
<dt>
<span class="term">
<code class="literal">delayed_unassigned_shards</code>
</span>
</dt>
<dd>
(integer) The number of shards whose allocation has been delayed by the
timeout settings.
</dd>
<dt>
<span class="term">
<code class="literal">number_of_pending_tasks</code>
</span>
</dt>
<dd>
(integer) The number of cluster-level changes that have not yet been
executed.
</dd>
<dt>
<span class="term">
<code class="literal">number_of_in_flight_fetch</code>
</span>
</dt>
<dd>
(integer) The number of unfinished fetches.
</dd>
<dt>
<span class="term">
<code class="literal">task_max_waiting_in_queue_millis</code>
</span>
</dt>
<dd>
(integer) The time expressed in milliseconds since the earliest initiated task
is waiting for being performed.
</dd>
<dt>
<span class="term">
<code class="literal">active_shards_percent_as_number</code>
</span>
</dt>
<dd>
(float) The ratio of active shards in the cluster expressed as a percentage.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-health-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/health.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _cluster/health</pre>
</div>
<div class="console_widget" data-snippet="snippets/1390.console"></div>
<p>The API returns the following response in case of a quiet single node cluster
with a single index with one shard and one replica:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "cluster_name" : "testcluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1,
  "delayed_unassigned_shards": 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch": 0,
  "task_max_waiting_in_queue_millis": 0,
  "active_shards_percent_as_number": 50.0
}</pre>
</div>
<p>The following is an example of getting the cluster health at the
<code class="literal">shards</code> level:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/health/twitter?level=shards</pre>
</div>
<div class="console_widget" data-snippet="snippets/1391.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="cluster-get-settings.html">« Cluster get settings API</a>
</span>
<span class="next">
<a href="cluster-reroute.html">Cluster reroute API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
